<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Cross Reference</title>
</head>
<body>
<h2>Cross Reference</h2>

<p>The <a
    href="javadoc/core/org/jbehave/core/reporters/CrossReference.html">CrossReference</a>
is a special report <a
    href="javadoc/core/org/jbehave/core/reporters/Format.html">Format</a>
that build a cross reference of stories being executed during the run.
It provides both JSON and XML representations, detailing both the
stories and scenarios run, as well as the step matches.</p>

<p>These representations can then be used by any app that can
navigate its contents and render it interactively.</p>

<p>A typical xref.json file is:</p>

<pre class="brush: plain">
{"xref": {
  "whenMade": 1298245533227,
  "createdBy": "JBehave",
  "meta": [
  ],
  "stories": [
    {
      "description": "",
      "narrative": "",
      "name": "unmatched_search_term.story",
      "path": "org/jbehave/examples/trader/stories/unmatched_search_term.story",
      "html": "org.jbehave.examples.trader.stories.unmatched_search_term.html",
      "meta": "",
      "scenarios": "Scenario:Search term does match examples table header\u000aG
iven that I am on Google's Homepage\u000aWhen I enter the search term ridiculou
sSearchTerm and proceed\u000aThen I should see ridiculous things\u000a\u000a\u0
00aScenario:Search term does not match examples table header and step is marked 
as pending\u000aGiven that I am on Google's Homepage\u000aWhen I enter the searc
h term ridiculousSearchTerm and proceed\u000aThen I should see ridiculous thin
gs\u000a\u000a\u000a",
      "passed": true,
      "pending": false
    }
  ],
  "stepMatches": [
    {
      "type": "GIVEN",
      "annotatedPattern": "that I am on Google's Homepage",
      "resolvedPattern": "that\\s+I\\s+am\\s+on\\s+Google's\\s+Homepage",
      "usages": [
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does match examples table header",
          "step": "Given that I am on Google's Homepage"
        },
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does not match examples table header and step
 is marked as pending",
          "step": "Given that I am on Google's Homepage"
        }
      ]
    },
    {
      "type": "WHEN",
      "annotatedPattern": "I enter the search term ridiculousSearchTerm and pr
oceed",
      "resolvedPattern": "I\\s+enter\\s+the\\s+search\\s+term\\s+ridiculousSear
chTerm\\s+and\\s+proceed",
      "usages": [
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does not match examples table header and step
 is marked as pending",
          "step": "When I enter the search term ridiculousSearchTerm and proce
ed"
        },
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does match examples table header",
          "step": "When I enter the search term ridiculousSearchTerm and proce
ed"
        }
      ]
    },
    {
      "type": "THEN",
      "annotatedPattern": "I should see ridiculous things",
      "resolvedPattern": "I\\s+should\\s+see\\s+ridiculous\\s+things",
      "usages": [
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does not match examples table header and step
 is marked as pending",
          "step": "Then I should see ridiculous things"
        },
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does match examples table header",
          "step": "Then I should see ridiculous things"
        }
      ]
    }
  ]
}}
</pre>

<h2>Configuration</h2>

<p>The CrossReference instance needs to configured in the <a
    href="javadoc/core/org/jbehave/core/reporters/StoryReporterBuilder.html">StoryReporterBuilder</a>:</p>
<pre class="brush: java">
public class TraderStories extends JUnitStories {
    
    @Override
    public Configuration configuration() {
        CrossReference xref = new CrossReference();
        return new MostUsefulConfiguration()
            .useStoryReporterBuilder(new StoryReporterBuilder()
                .withCrossReference(xref)) 
            .useStepMonitor(xref.getStepMonitor());                               
    }
}
</pre>

<p>If the CrossReference is configured, the JSON and XML
representations are generated automatically in the JBehave report view
directory (<b>target/jbehave/view</b> by default) by the JUnit-based
ConfigurableEmbedder, i.e. JUnitStory and JUnitStories. In other case, you
may generate them on demand via the Embedder method <b>generateCrossReference()</b>.</p>

<p>Optionally, CrossReference can be configured to update file output after each story and to output 
to JSON or XML only (instead of both).  Moreover, the user can choose to exclude stories when there are no executed scenarios</p>

<p>Note that in the above code fragment we are only focusing on the
configuration of the CrossReference. In particular, you may be chaining
more than one step monitor together in the useStepMonitor(..) line.
Also, there will be typically other methods to implement in JUnitStories
for finding stories and other configuration elements to specify.
<p>

<h2>Examples</h2>

<p>Examples of configuration of CrossReference can be found in <a href="running-examples.html">core example</a> and the
 <a href="https://github.com/jbehave/jbehave-tutorial">JBehave Tutorial</a>.</p>

</body>
</html>
